WorldPay API
Description
How you can access WorldPay's API in order to create credit card and ACH transactions for your app.
Introduction
An Xbasic class called WorldPayAPI::SoapActions supports the WorldPay Online Commerce Suite. All of the documented methods of the WorldPay SOAP API are included in this class. Click here to see the official WorldPay API documentation. WorldPay is one of the world's leading payment companies. The WorldPay integration within Alpha Anywhere allows developers to process credit card and ACH transactions easily through WorldPay. You will need to setup a WorldPay merchant account to get started. See Alpha Anywhere / WorldPay Info Before using the WorldPayAPI::SoapActions class you will need to make note of your WorldPay account Id, account subid( if any) and merchant pin. If you are testing with a sandboxed WorldPay developer account, you will also need to provide the test credit card information that will be provided by WorldPay.
To instantiate a WorldPayAPI::SoapActions object
dim wp as WorldPayAPI::SoapActions = new WorldPayAPI::SoapActions()
You will be passing in a dot variable that contains (at a minimum) the required properties for each of the WorldPayAPI::SoapActions methods.
The WorldPayAPI::SoapActions methods include:
Credit Card Transactions
processCCSale
Process a credit card sale
Required Properties: acctid, subid, merchantpin, amount, ccnum, expmon, expyear, ccname
Response Object: ProcessResult
processCCAuth
Authorize a credit card sale
Required Properties: acctid, subid, merchantpin, amount, ccnum, expmon, expyear, ccname
Response Object: ProcessResult
processCCCredit
Process a standalone credit card credit
Required Properties: acctid, subid, merchantpin, amount, ccnum, expmon, expyear, ccname
Response Object: ProcessResult
processCCPost
Process a post/capture of a previous credit card auth
Required Properties: acctid, subid, merchantpin, amount, orderid, historyid
Response Object: ProcessResult
processAuthReverse
Perform a reversal of a credit card auth
Required Properties: acctid, subid, merchantpin, amount, orderid, historyid
Response Object: ProcessResult
processVoid
Void a previous auth or sale
Required Properties: acctid, subid, merchantpin, amount, orderid, historyid
Response Object: ProcessResult
processCredit
Issue credit for a previous CC or ACH Sale
Required Properties: acctid, subid, merchantpin, amount, orderid, historyid
Response Object: ProcessResult
Gift Card Transactions
processSVSale
Process a gift card sale
Required Properties: acctid, subid, merchantpin, amount, ccnum, expmon, expyear, ccname
Response Object: ProcessResult
processSVAddValue
Add value to a gift card
Required Properties: acctid, subid, merchantpin,amount, ccnum, expmon, expyear, ccname
Response Object: ProcessResult
processSVIssue
Issue a new gift card
Required Properties: acctid, subid, merchantpin,amount, ccnum, expmon, expyear, ccname
Response Object: ProcessResult
processSVDeactivate
Deactivate a gift card
Required Properties: acctid, subid, merchantpin, amount, ccnum, expmon, expyear, ccname
Response Object: ProcessResult
processSVRefund
Refund a gift card transaction
Required Properties: acctid, subid, merchantpin, amount, orderid, historyid
Response Object: ProcessResult
Stored Profiles
processProfileSale
Issue CC, ACH or ExtACH sale using a stored profile.
Required Properties: acctid, subid, merchantpin, amount, userprofileid, last4digits
Response Object: ProcessProfileResult
processProfileCredit
Issue credit using a stored profile
Required Properties: acctid, subid, merchantpin, amount, userprofileid, last4digits
Response Object: ProcessProfileResult
processProfileUpdate
Updates a stored profile
Required Properties: acctid, subid, merchantpin, userprofileid, last4digits, accttype, profilenobill
Response Object: ProcessProfileResult
processCCProfileAdd
Store credit card using a stored profile
Required Properties: acctid, subid, merchantpin, ccnum, expmon, expyear, ccname
Response Object: ProcessProfileResult
processCKProfileAdd
Store ACH using a stored profile
Required Properties: acctid, subid, merchantpin, ckname, ckaba, ckno, ckacct
Response Object: ProcessProfileResult
processExtACHProfileAdd
Store ExtACH using a stored profile
Required Properties: acctid, subid, merchantpin, ckname, ckaba, ckno, ckacct
Response Object: ProcessProfileResult
processProfileDelete
Delete a stored profile
Required Properties: acctid, subid, merchantpin, userprofileid, last4digits, ipaddress
Response Object: ProcessProfileResult
processProfileRetrieve
Retrieves the account number, address and billing info
Required Properties: acctid, subid, merchantpin, userprofileid, last4digits
Response Object: ProcessProfileResult
processAccountLookup
Performs an account lookup for the stored profile
Required Properties: acctid, subid, merchantpin, ssnum, billaddress
Response Object: ProcessAccountLookupResult
Debit Card Transactions
processDebitSale
Process PIN-Debit sale transaction
Required Properties: acctid, subid, merchantpin, amount, customerid, swipedata
Response Object: ProcessResult
processDebitAuth
Process PIN-Debit auth transaction
Required Properties: acctid, subid, merchantpin, amount, customerid, swipedata
Response Object: ProcessResult
processDebitReturn
Process PIN-Debit return transaction
Required Properties: acctid, subid, merchantpin, amount, customerid, orderid, historyid
Response Object: ProcessResult
processDebitVoid
Process PIN-Debit void transaction
Required Properties: acctid, subid, merchantpin, amount, orderid, historyid
Response Object: ProcessResult
processDebitPost
Issue PIN-Debit post
Required Properties: acctid, subid, merchantpin, amount, orderid, historyid
Response Object: ProcessResult
processDebitPinless
Issue pinless debit
Required Properties: acctid, subid, merchantpin, amount, ccnum, expmon, expyear, ccname
Response Object: ProcessResult
processDebitPinlessCredit
Issue pinless credit
Required Properties: acctid, subid, merchantpin, amount, orderid, historyid
Response Object: ProcessResult
ACH Transactions
processACHSale
Process a ACH sale
Required Properties: acctid, subid, merchantpin, amount, ckname, ckaba, ckno, ckacct, cktype
Response Object: ProcessResult
processVoid
Void a previous check authorization
Required Properties: acctid, subid, merchantpin, amount, orderid, historyid
Response Object: ProcessResult
processCredit
Issue credit for a previous ACH sale
Required Properties: acctid, subid, merchantpin, amount, orderid, historyid
Response Object: ProcessResult
processACHCredit
Process a standalone ACH credit
Required Properties: acctid, subid, merchantpin, amount, ckname, ckaba, ckno, ckacct, cktype
Response Object: ProcessResult
processACHVerification
Process a ACH verification
Required Properties: acctid, subid, merchantpin, amount, ckname, ckaba, ckno, ckacct, cktype
Response Object: ProcessResult
Check 21 Transactions
processC21Sale
Process a check 21 ICL/RCC sale
Required Properties: acctid, subid, merchantpin, amount, ckname, firstname, lastname, ckaba,
Response Object: ProcessResult
-
-
Required Properties: ckno, ckacct, ckaccttype, billstreet, housenumber, companyname, phone,
Response Object:
-
-
Required Properties: email, billaddress
Response Object:
processC21Credit
Process a check 21 ICL/RCC credit
Required Properties: acctid, subid, merchantpin, amount, orderid, historyid
Response Object: ProcessResult
processC21Void
Process a check 21 ICL/RCC void
Required Properties: acctid, subid, merchantpin, amount, orderid, historyid
Response Object: ProcessResult
Recurring Records
processRecurAdd
Creates a recurring record without an initial transaction
Required Properties: acctid, subid, merchantpin, accttype, acctdata1, acctdata2, acctname,
Response Object: ProcessResult
-
-
Required Properties: recurring, recur_nextbillingdate
Response Object:
processRecurUpdate
Updates a recurring record
Required Properties: acctid, subid, merchantpin, orderid
Response Object: ProcessResult
processRecurCancel
Cancels an active recurring record
Required Properties: acctid, subid, merchantpin, orderid, canceltype
Response Object: ProcessResult
3rd Party Check Processing
processExtACHConsumerDisbursement
Process a standalone ext ACH consumer disbursement
Required Properties: acctid, subid, merchantpin, amount, ccnum, expmon, expyear, ccname
Response Object: ProcessResult
processExtACHCredit
Process an extented ACH credit
Required Properties: acctid, subid, merchantpin, amount, ccnum, expmon, expyear, ccname
Response Object: ProcessResult
processExtACHSale
Process an extended ACH sale
Required Properties: acctid, subid, merchantpin, amount, ccnum, expmon, expyear, ccname
Response Object: ProcessResult
processExtACHVoid
Process sn extended ACH void
Required Properties: acctid, subid, merchantpin, amount, ccnum, expmon, expyear, ccname
Response Object: ProcessResult
Response Objects
Builtin Xbasic CallResult
returnDataValue
Contains one of the 3 possible WorldPay response objects, dependent upon the API method called.
ProcessResult
ProcessProfileResult
ProcessAccountLookupResult
Canceled
Value is .T. if the API call is canceled otherwise .F.
Error
Value is .T. on error condition, otherwise .F.
NativeCode
Native response code value returned from the request, if any.
NativeText
Native text value returned from the request, typically Success or Declined.
Code
Value is response code value of the API call, if any.
Text
Value indicates the status of the API call.
WorldPay Response Objects:
ProcessResult
status
Declined or approved.
result
Colon delimited result code.
total
Floating point number indicating transaction dollar amount in US dollars. Round to 2 decimal places as required.
orderid
Order key id of the original transaction.
historyid
History key id of the original transaction.
authcode
Colon delimited result code.
merchantordernumber
Customer's unique alpha-numeric number.
acctid
If subid LoadBalancing is enabled, includes the acctid used for the transaction.
subid
If subid LoadBalancing is enabled, includes the subid used for transaction.
transdate
Date and time of the transaction in ISO 8601 format. See WorldPay doc for details.
paytype
Payment type used to process the transaction (MasterCard, Visa, Amex, etc.)
duplicate
0 or 1, 1 indicates a duplicate was detected.
avsresult
AVS result code.
cvv2result
CVV2 result code.
batchnumber
Batch number asssigned to the transaction.
last4digits
Last four digits of the credit card or ACH transaction.
entrymethod
Indicates how the transaction was processed.
partialapproval
0 or 1, 1 indicates a partial amount was received.
actioncode
Code identifying partial approval amount.
balance
Balance inquiry amount.
recurbillingamount
Recurring amount.
recurextbillingdate
Date to recur.
recurbillingcycle
Recur cycle.
recurbillingmax
Max number of recurrings.
recurcanceldate
Cancel date of recurrings.
recurlastattempted
Date of last recurring attempted.
recurbillingstatus
Status of recurring.
recurtotalaccept
Total number of approved recurrings processed.
achrcode
ACH return code
transactiontype
Type of transaction.
additionaldata
XML document containing additional data. See WorldPay SOAP Integration Guide doc.
ProcessProfileResult
status
Declined or approved.
result
Colon delimited result code. Round to 2 decimal places as required.
total
Floating point number indicating transaction dollar amount in US dollars. Round to 2 decimal places as required.
orderid
Order key id of the original transaction.
historyid
History key id of the original transaction.
authcode
Colon delimited result code.
merchantordernumber
Customer's unique alpha-numeric number.
transdate
Date and time of the transaction in ISO 8601 format. See WorldPay doc for details.
paytype
Payment type used to process the transaction (MasterCard, Visa, Amex, etc.)
duplicate
0 or 1, 1 indicates a duplicate was detected.
userprofileid
User profile id of the transaction.
last4digits
Last four digits of the credit card or ACH transaction.
acctid
If subid LoadBalancing is enabled, includes the acctid used for the transaction.
subid
If subid LoadBalancing is enabled, includes the subid used for transaction.
avsresult
AVS result code.
cvv2result
CVV2 result code.
batchnumber
Batch number asssigned to the transaction.
entrymethod
Indicates how the transaction was processed.
partialapproval
0 or 1, 1 indicates a partial amount was received.
actioncode
Code identifying partial approval amount.
additionaldata
XML document containing additional data. See WorldPay SOAP Integration Guide doc.
billaddr1
Billing address.
billaddr2
Billing address (extended).
billcity
Billing city.
billstate
Billing state.
ProcessAccountLookupResult
status
Declined or approved.
result
Colon delimited result code.
orderid
Order key id of the original transaction.
historyid
History key id of the original transaction.
authcode
Colon delimited result code.
paytype
Payment type used to process the transaction (MasterCard, Visa, Amex, etc.)
last4digits
Last four digits of the credit card or ACH transaction.
entrymethod
Indicates how the transaction was processed.
transactiontype
Type of transaction.
firstname
Customer's first name
lastname
Customer's last name
phone
Customer's phone
addr1
Customer's address 1
addr2
Customer's address 2
city
Customer's city
state
Customer's state
zipcode
Customer's zip code / postal code
country
Customer's country
additionaldata
XML document containing additional data. See WorldPay SOAP Integration Guide doc.
WorldPay:: Classes
WorldPay::Recur
create
Type int: A value of 1 will create the recurring entry
billingcycle
Type int. Coded value, 0 through 11, see WorldPay doc for details.
billingmax
Type int. Number of max re-bills (1,2,3, -1 = unlimited)
start
Type int. Number of days to start the recur.
amount
Type float. Recurring amount.
WorldPay::Address
WorldPay::CustomEmail
emailto
Type string. Email address to send consumer email recipt, default is ci_email address.
emailfrom
Type string. Return email address on consumers email receipt. Default is [email protected].
emailsubject
Type string. Subject line on the consumers email receipt. Default is Payment Receipt #xyz
emailtext
Type string. Email body text on consumers receipt. Default is generic receipt message.
WorldPay::CustomFields
WorldPay::HotelLodging
chargetypeamx
Type string. Code indicating type of charge. 1= Hotel, 2 = Restaurant, 3 = Gift Shop
roomrateamt
Type string. Room rate in US dollars, ex. 0.00.
checkindate
Type string. Check in date (yymmdd)
checkoutdate
Type string. Check out date (yymmdd)
purchaseid
Type string. Hotel folio number (25 alphanumeric chars max)
pproperty
Type string. Prestigious property indicator, used by Visa only, see WorldPay doc.
extracharges
Type string. Coded 6 1-digit codes for charges, see WorldPay doc.
WorldPay::AutoRental
rentalagreementnum
Type string. 25 alphanumeric chars max
rentalrate
Type string. Rental rate amount
noshowprogind
Type char. Value of "1" indicates a no show charge
extracharges
Type char. Coded character value, "0" thru "5", see WOrldPay doc.
rentaldate
Type string. Rental start date, yy/mm/dd
rentalreturndate
Type string. Rental end date, yy/mm/dd
rentername
Type string. Renter's name
rentalreturncity
Type string. Return city
rentalreturnstatecountry
Type string. Return State/Country, ISO3 coding
rentalreturnlocationid
Type string. 10 char location id
WorldPay::AutoRepair
vin
Type string. Vehicle identification number
odometer
Type string. Odometer mileage
workorder
Type string. Merchant's work order number
unit
Type string. Truck/Vehicle unit number
repaircode
Type string. Code to identify type of repair
WorldPay::FSA
healthcareflag
Type int. 1 = on, 0 = off
rxamount
Type float. Qualified presecription amount
clinicamount
Type float. Qualified medical clinic amount
visionamount
Type sfloat. Qualified vision amount
dentalamount
Type float. Qualified dental amount
WorldPay::PurchaseCardLevel2
pocustomerrefid
Type string. Cardholders customer id or reference number
taxamount
Type float. Total tax charged fot the transaction
taxexempt
Type int. 1 = tax exempt, 0 = taxable
WorldPay::PurchaseCardLevel3
lineitems
Type string. See WorldPay doc, Appendix F
WorldPay::Restaurant
gratuityamount
Type float. The gratuity amount
WorldPay::FleetCardData
atpump
Type int. Coded value, 1 = yes, 0 = no
idnumber
Type string. User id
vehicleid
Type string. Vehicle id
driverid
Type string. Driver id
odometerreading
Type string. Odometer reading
miscnumericdata
Type string. Customer data
jobnumber
Type string. Job number
purchasedevsequencenumber
Type string. Purchase device sequence number
departmentnumber
Type string. Department number
Example Code
The Xbasic example code below can be used to test numerous methods of the WorldPayAPI::SoapActions class. You will need to provide your own merchantpin, test credit card info, acctid,
dim runTests as l = .t. if (runTests) dim cr as CallResult dim p as p p.merchantpin = "1234567890" p.ccname = "WORLDPAY/TEST" p.amount = 3.98 p.expmon = 12 p.expyear = 2015 p.companyname = "enterCompanyNameHere" p.phone = "222-222-2222" p.acctid = "enterYourAcctIdHere" p.subid = "enterYourSubIdHere" 'for testing credits/returns p.historyid = "enterHistoryIdHere" p.orderid = "enterOrderIdHere" ' for testing profile update method p.accttype = 1 p.profilenobill = 0 '// ------ TEST CARD DATA ---------- ** 'uncomment / comment out as required for testing ' test Visa 'p.ccnum = "enterVisaCardNumHere" ' test Amex p.ccnum = "enterAmexCardNumHere" p.userprofileid = "enterUserProfileIdHere" p.last4digits = "entelast4DigitsHere" p.ipaddress = "enterIPAddressHere" ' test Discover 'p.ccnum = "enterDiscoverCardNumHere" ' ------END TEST CARD DATA -------- ' instantiate wp object from class dim wp as WorldPayAPI::SoapActions = new WorldPayAPI::SoapActions() ' test custom fields, not required for all methods. Notice the use of WorldPay::CustomFields class p.customizedfields = new WorldPay::CustomFields() p.customizedfields.custom1 = "My custom Field #1" p.customizedfields.custom2 = "My custom Field #2" ' test custom email, not required for all methods. Notice the use of WorldPay::CustomEmail class p.customizedemail = new WorldPay::CustomEmail() p.customizedemail.emailto = "[email protected]" ' test bill and ship addresses, not required for all methods. Notice the use of the WorldPay::Address class p.billaddress = new WorldPay::Address() p.billaddress.addr1 = "1 Bay Road" p.billaddress.city = "Duxbury" p.billaddress.state = "MA" p.billaddress.zip = "02332" p.shipaddress = new WorldPay::Address() p.shipaddress.addr1 = "700 Congress St." p.shipaddress.city = "Fairfield" p.shipaddress.state = "CT" p.shipaddress.zip = "06430" 'uncomment / comment out as required for testing cr = wp.processCreditCardSale(p) 'cr = wp.processCreditCardAuth(p) 'cr = wp.processAuthReverse(p) 'cr = wp.processVoid(p) 'cr = wp.processCredit(p) 'cr = wp.processCCProfileAdd(p) 'cr = wp.processProfileSale(p) 'cr = wp.processProfileDelete(p) 'cr = wp.processProfileUpdate(p) dim msgTmpl as c dim resultType as c = trim(cr.ReturnDataValue) select case resultType = "ProcessResult" msgTmpl = "Status: "+ cr.ReturnDataValue.status + crlf()+ \ "Paytype "+ cr.ReturnDataValue.paytype + crlf()+ \ "Total: "+ round(cr.ReturnDataValue.total,2) + crlf()+ \ "Last 4 digits: " + cr.ReturnDataValue.last4digits + crlf()+ \ "AuthCode: " + cr.ReturnDataValue.authcode + crlf() + \ "OrderId: "+ cr.ReturnDataValue.orderid + crlf()+ \ "HistoryId: "+ cr.ReturnDataValue.historyid case resultType = "ProcessProfileResult" msgTmpl = "Status: "+ cr.ReturnDataValue.status + crlf()+ \ "Paytype "+ cr.ReturnDataValue.paytype + crlf()+ \ "Total: "+ round(cr.ReturnDataValue.total,2) + crlf() + \ "Last 4 digits: " + cr.ReturnDataValue.last4digits + crlf()+ \ "AuthCode: " + cr.ReturnDataValue.authcode + crlf() + \ "OrderId: "+ cr.ReturnDataValue.orderid + crlf() + \ "HistoryId: "+ cr.ReturnDataValue.historyid + crlf() + \ "UserProfileId: "+cr.ReturnDataValue.userprofileid case resultType = "ProcessAccountLookupResult" msgTmpl = "Status: "+ cr.ReturnDataValue.status + crlf()+\ "Paytype "+ cr.ReturnDataValue.paytype + crlf()+ \ "OrderId: "+ cr.ReturnDataValue.orderid+crlf()+ \ "HistoryId: "+ cr.ReturnDataValue.historyid + \ "AuthCode: " + cr.ReturnDataValue.authcode + crlf() + \ "Last 4 digits: " + cr.ReturnDataValue.last4digits + crlf()+ \ "First name: " + cr.ReturnDataValue.firstname + crlf()+ \ "Last name: " + cr.ReturnDataValue.lastname + crlf()+ \ "Phone : " + cr.ReturnDataValue.phone + crlf()+ \ "Address1: " + cr.ReturnDataValue.addr1 + crlf()+ \ "Address2: " + cr.ReturnDataValue.addr2 + crlf()+ \ "City: " + cr.ReturnDataValue.city + crlf()+ \ "State: " + cr.ReturnDataValue.state + crlf()+ \ "Zip code: " + cr.ReturnDataValue.zipcode + crlf()+ \ "Country: " + cr.ReturnDataValue.country + crlf() case else msgTmpl = "Error, unknown result type." end select ui_msg_box("WorldPay Results",msgTmpl) end if